home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -screenplay- / hd_installers / -whdload- / whdload_dev / patcher1.04.lha / Patcher1.04 / PatcherDeveloper.readme < prev    next >
Text File  |  1997-03-26  |  11KB  |  267 lines
  1. Programmers description:
  2. MAKECOMPTAB gives the differences in a way which is used in a module. 
  3. Options are:
  4. MAKECOMPTAB ?    - gives a short description
  5. MAKECOMPTAB "original" "patchedfile" {"tableoutput"}
  6.     - compares original with patched file and writes the differences 
  7.       to tableoutput, if specified.
  8. Commandline for Directoryopus is: Makecomptab "{fu}" "{d}{ou}" "RAM:table_{o}"
  9. It compares the selected file in the source window with the equal named 
  10. file in the destination window and writes the table of differences to RAM:.
  11.  
  12. If you dont understand the following text, please look at the examples 
  13. for modules. I find it easier to see an example and a description 
  14. together cause it is complicate to explain some things here under-
  15. standable.
  16.  
  17. Structure of a module for THE DEPROTECTOR:
  18.     MOVEQ.L    #20,D0        ;four fillbytes (reserved!)
  19.     RTS
  20.     DC.L    TABLE        ;pointer on the tagarray
  21.     DC.B    'PTCH'        ;for recognizing module
  22.     ...
  23. TABLE    {TAGS}
  24.     DC.L    TAG_DONE
  25.     ...
  26.  
  27.  
  28. Supported tags:
  29.  
  30. TAG_DONE        = $00000000
  31. Finishes the tagtable.
  32.  
  33. PCH_ADAPTOR        = $80004451
  34.     DC.L    {^yourname}
  35. Name of the people which did the fixing work :). Maximally 2 lines of 
  36. appr. 40 characters, each line finished by $A and the text ended with $0. 
  37. This tag is necessary.
  38.  
  39. PCH_NAME        = $80004458
  40.     DC.L    {^parametername}
  41. Name of the game, max. 1 line of appr. 40 characters. The filename of the 
  42. parameter itself is meaningless. This tag is necessary.
  43.  
  44. PCH_FILECOUNT        = $80004450
  45.     DC.L    {#filecount}    
  46. Number of cycles to execute, mostly equal to the total number of the files 
  47. to modify or save (all disks added). This tag is necessary.
  48.  
  49. PCH_FILENAME        = $80004454
  50.     DC.L    {^array of ^filenames}
  51. Points on an array of the pointers on the filenames (with path). 
  52.  
  53. PCH_DISKNAME        = $80004452
  54.     DC.L    {^array of ^disknames}
  55. Points on an array of the pointers on the disknames (without : !!).
  56.  
  57. PCH_CHANGES        = $80004456
  58.     DC.L    {^array of ^changestables}
  59. Points on an array of the pointers on the changestables obtained by 
  60. MAKECOMPTAB.
  61.  
  62. PCH_CHECKDISK        = $80004453
  63.     DC.L    {^array of ^ckeckroutines}
  64. Points on an array of the pointers on the customcheckroutines. This tag is 
  65. only necessary if you want to recognize a nonstandard disk (but i prefer to 
  66. recognize the disk in the PCH_SPECIAL-routine).
  67.  
  68. PCH_MINVERSION        = $80004459
  69.     DC.L    {^versionstring}
  70. If your parameter requires a feature of a higher version of THE PATCHER, 
  71. you can set a versionstring. Useful eg for commandline-parameters.
  72. Stringformat: DC.B    'V1.03',0
  73.  
  74. PCH_PROCESSING        = $80004457
  75.     DC.L    {^array of ^processingroutines}
  76. Points on an array of the pointers on specialroutines. Such a specialroutine
  77. can be a decryptroutine. For more information look at the parameter 
  78. of populous.
  79.  
  80. PCH_LOADOFFSET        = $8000445A
  81.     DC.L    {^array of offsets}
  82. Points on an array of offsets of the loaded file, this means the file 
  83. will be appended on that space. Required for changing the startup-sequence
  84. if you want to insert a line at the top (for ex. FIRST{Return}, then you 
  85. have an offset of 6).
  86.  
  87. PCH_APPENDSPACE        = $8000445E
  88.     DC.L    {^array of space}
  89. Points on an array of space appended on the loaded file, this means the space 
  90. will be appended on that file. Required for changing the startup-sequence
  91. if you want to insert a line at the bottom (for ex. LAST{Return}, then you 
  92. have an space of 5).
  93.  
  94. PCH_STATE        = $8000445C
  95.     DC.L    {^array of ^statetexts}
  96. Points on an array of pointers on statetexts. Required for nonstandard 
  97. disks, when you need a formatconversion and will have to read the original 
  98. disk so that you have to write "Please insert your original writeprotected 
  99. disk." instead of "Please insert a copy of your disk and wait for 
  100. processing.".
  101.  
  102. PCH_STATE2        = $8000445D
  103.     DC.L    {^array of ^statetexts2}
  104. Points on an array of pointers on statetexts. Required for nonstandard 
  105. disks, when you need a formatconversion and will have to write to the  
  106. destination disk so that you must write "Please insert your destination 
  107. disk." instead of "Please insert a copy of your disk and wait for 
  108. processing.".
  109.  
  110. PCH_INIT        = $8000445B
  111.     DC.L    {^initialisation routine}
  112. If a parameter must be initialized, you can do that here.
  113.  
  114. PCH_SPECIAL        = $80004455
  115.     DC.L    {^array of ^specialroutines}
  116. Here could be routines for loading data of a nonstandard disk.
  117.  
  118. PCH_SAVEPGM        = $80004464
  119.     DC.L    {^array of ^specialroutines}
  120. Here could be routines for saving data on a nonstandard disk.
  121.  
  122. PCH_SAVEDATA        = $8000445F
  123.     DC.L    {^array of ^datatables}
  124. Needed if you have to save an additional file to disk.
  125.  
  126. PCH_DATALENGTH        = $80004460
  127.     DC.L    {^array of lengths of data to save}
  128. Needed when a formatconversion is made or you have to save an additional 
  129. file on the disk. Or you use it to ensure the correct version of the 
  130. game.
  131.  
  132. PCH_BOOTBLOCK        = $80004461
  133.     DC.L    {^array of ^bootblocks}
  134. Saves the declared bootblock on disk. The Bootblock has to be in chipmemory!
  135.  
  136. PCH_FINISH        = $80004462
  137.     DC.L    {^finishing routine}
  138. If a parameter has to do some finishing-code (eg freeing self-allocated 
  139. memory), you can do that here.
  140.  
  141. PCH_ERRORINPARAMETER    = $80004463
  142.     DC.L    {^error routine}
  143. If an error occured and a parameter has to do some finishing-code, you can do 
  144. that here.
  145.  
  146.  
  147. Running:
  148. It clears the area given by PTB_SPACE.
  149. At first it checks if an initroutine (PCH_INIT) is present.
  150. Then it detects the number of cycles (PCH_FILECOUNT).
  151. Now begins the cyclic program:
  152.  It tries to write out the state (PCH_STATEARRAY).
  153.  Then it tries to get the diskname (PCH_DISKNAMEARRAY) and to check for the 
  154.  diskvolume.
  155.  Then it would execute a customcheckroutine for the disk (PCH_CHECKDISKARRAY).
  156.  Then it gets the filename (PCH_FILENAMEARRAY).
  157.   If there is a tag for a customroutine (PCH_SPECIALARRAY), it would 
  158.   happen the following:
  159.    It accounts the RAM given by PCH_DATALENGTH (obviously in that case it is 
  160.    needed). PTB_ADDRESSOFFILE points on that area.
  161.    It doesnt load the file given by the filename, but executes your 
  162.    customroutine, which could be a loading routine.
  163.    Now it writes out the save state (PCH_STATEARRAY2) if present.
  164.    Then it executes a routine if PCH_PROCESSINGARRAY is present. 
  165.    Then it mades the changes given by PCH_CHANGESARRAY.
  166.    Then it will execute the routine given by PCH_SAVEPGM.
  167.    Then it will save the file (only if a filename was given). Cycle ends.
  168.   If there is a tag for saving a bootblock (PCH_BOOTBLOCKARRAY), 
  169.    it tries to write out the message of PCH_STATEARRAY2.
  170.    Then the bootblock will be saved. Cycle ends.
  171.   If there is a tag for saving a file (PCH_SAVEDATA),
  172.    the length of that file will be given by PCH_DATALENGTH.
  173.    It tries to write out the message given by PCH_STATEARRAY2.
  174.    Then the file will be saved.
  175.   Otherwise it will execute the following:
  176.    It gets the length of the file.
  177.    Then it tries to detect PCH_LOADOFFSETARRAY and PCH_APPENDSPACEARRAY and 
  178.    evaluates the filelength.
  179.    Then it compares the filelength with the length given by PCH_DATALENGTH
  180.    (if present) and cancels the parameter processing if not equal.
  181.    Then it would account the RAM evaluated and load that file.
  182.    Now it writes out the save state (PCH_STATEARRAY2) if present.
  183.    Then it executes a routine if PCH_PROCESSINGARRAY is present. See also 
  184.    the example of Populous.
  185.    Then it makes the changes given by PCH_CHANGESARRAY.
  186.    Then it will save the file.
  187. Here ends the cyclic program.
  188. If there is a finishing routine {PCH_FINISH} it will be executed.
  189. Source- and destinationdevice will be closed, if it were opened.
  190. It is impossible to check all correct combinations, so FIRST think about it 
  191. and then plan a module. When you give the tag PCH_SAVEDATA and no filename, 
  192. an error will occur or the program crashes!
  193.  
  194. In the routines in the cyclic programexecution D6 gives the actual cycle. Look
  195. at the example of imagergemx.
  196. On all moduleroutines A5 points on the following area:
  197. PTB_DOSBASE        = $0    Base of the dos.library.
  198. PTB_ADDRESSOFFILE    = $4    Points on the filedata.
  199. PTB_INTUITIONBASE    = $8    Base of the intuition.library.
  200. PTB_GFXBASE        = $C    Base of the graphics.library.
  201. PTB_WINDOW        = $10    Points on the structure Window.
  202. PTB_FILENAME        = $14    Points on the filename.
  203. PTB_FULLNAME        = $18    Points on the filename with the volumename.
  204. PTB_FILESIZE        = $1C    Gives the filesize.
  205. PTB_DISKNAME        = $20    Points on the volumename.
  206. PTB_OPENDEVICE        = $24    Points on a routine to open the device 
  207.                 specified in the CLI. Needed only if you 
  208.                 have to convert a nonstandard disk.
  209.                 D0 = 0    opens for source
  210.                 D0 = 1    opens for destination
  211. PTB_DEVICESOURCEPTR    = $28    If you called PTB_OPENDEVICE with D0=0, this 
  212.                 shows the base of the source device, otherwise 
  213.                 it is 0.
  214. PTB_DEVICEDESTPTR    = $2C    If you called PTB_OPENDEVICE with D0=1, this 
  215.                 shows the base of the destination device, 
  216.                 otherwise it is 0.
  217. PTB_SPACE        = $30    Points on a chipmem-area of $C000 bytes for 
  218.                 buffering any data (not used in the main 
  219.                 program).
  220. PTB_FORMATDEST        = $34    Formats a dd-disk in the destination drive,
  221.                 when called with D0=0. Returns D0=0 on success.
  222. PTB_REQUEST        = $38    Shows a Ok-Cancel-requester. Two lines of
  223.                 text are allowed, given in A0 and A1.
  224.                 Returns D0=0 on Ok and -1 on Cancel.
  225. New in version 1.02:
  226. PTB_FSSMSOURCEPTR    = $3C    If PTB_OPENDEVICE was successfully called the
  227. PTB_FSSMDESTPTR        = $40    corresponding PTB_FSSM*PTR points on the
  228.                 FileSystemStartupMessage-structure of that
  229.                 device.
  230. PTB_INHIBITDRIVE    = $44    Inhibits the source-drive, when called with
  231.                 D0=0 and the destination-drive when called 
  232.                 with D0=1. Returns D0=0 on success.
  233. PTB_ENABLEDRIVE        = $48    Enables the inhibited source-drive when 
  234.                 called with D0=0 and the destinationdrive when
  235.                 called with D0=1. Returns D0=0 on success.
  236.  
  237. New in version 1.03:
  238. PTB_CRC16        = $4C    Returns in D0 a 16-bit-CRC of an area given by
  239.                 a pointer in A0    and a length in D0.
  240.  
  241. You can use all registers in your module, the regs are rescued on 
  242. the stack before executing your program.
  243.  
  244. All routines must return 0 in D0 if all went ok.
  245.  
  246. The parameters may contain all kind of hunks and memorytypes.
  247.  
  248. Please dont change the tags itself of a parameter while execution. The 
  249. value of the tags and the tables itself may be changed in execution 
  250. (see at the example of imagernitro), but AT LEAST ONE cycle before they 
  251. are needed, eg you may change stuff for cycle 1 in PCH_INIT, stuff for 
  252. cycle 3 in cycle 2 and so on. The only exception from that rule is 
  253. PCH_CHANGESTABLE which may be changed at any time before use.
  254. If you have to convert a nst-disk to files and you get your filenames from
  255. the disk, you can use 2 spaces for filenames alternating and set the one 
  256. which is unused in the current cycle.
  257.  
  258. Sorry, but all examples can be assembled only with uppercase=lowercase.
  259.  
  260. Tricks:
  261. If you want to insert a line at the top of the startup-sequence, please 
  262. change the startup-sequence once to the destination and once insert only
  263. fillbytes (for ex. @) instead. Then use the true startup-sequence as 
  264. patchfile and the dummy one as original with MAKECOMPTAB and you will get 
  265. your changestable.
  266.  
  267.